<html>
    <head>
    <link rel="stylesheet" href="lmm.css" type="text/css" />
    </head>
<body class="lmm">
<!-- This file is part of the Lisp Machine manual.		-*-Text-*- -->

<div class='chapter'>4. Closures</div><p class='cindent'><!-- "closure" -->

	A <font class="italic">closure</font> is a type of Lisp functional object useful
for implementing certain advanced access and control structures.
Closures give the programmer more explicit control over the
environment, by allowing him to "save up" the environment created
by the entering of a dynamic contour (i.e. a <font class="lisp">lambda</font>, <font class="lisp">do</font>,
<font class="lisp">prog</font>, <font class="lisp">progv</font>, <font class="lisp">let</font>, or any of several other special
forms), and then use that environment
elsewhere, even after the contour has been exited.

<div class='section'>4.1 What a Closure Is</div>
	There is a view of lambda-binding which we will use in this
section because it makes it easier to explain what closures do.  In
this view, when a variable is bound, a new value cell is created for it.
The old value cell is saved away somewhere and is inaccessible.  Any
references to the variable will get the contents of the new value cell,
and any <font class="lisp">setq</font>'s will change the contents of the new value cell.
When the binding is undone, the new value cell goes away, and the old
value cell, along with its contents, is restored.

	For example, consider the following sequence of Lisp forms:
<pre class="lisp">
(setq a 3)

((lambda (a)
    (print (+ a 6)))
 10)

(print a)
</pre>
Initially there is a value cell for <font class="lisp">a</font>, and the <font class="lisp">setq</font> form makes
the contents of that value cell be <font class="lisp">3</font>.  Then the
<font class="lisp">lambda</font>-combination is evaluated.  <font class="lisp">a</font> is bound to <font class="lisp">10</font>: the old
value cell, which still contains a <font class="lisp">3</font>, is saved away, and a new
value cell is created with <font class="lisp">10</font> as its contents.  The reference to
<font class="lisp">a</font> inside the <font class="lisp">lambda</font> expression evaluates to the current binding
of <font class="lisp">a</font>, which is the contents of its current value cell, namely
<font class="lisp">10</font>.  So <font class="lisp">16</font> is printed.  Then the binding is undone, discarding
the new value cell, and restoring the old value cell which still
contains a <font class="lisp">3</font>.  The final <font class="lisp">print</font> prints out a <font class="lisp">3</font>.

	The form <font class="lisp">(closure <font class="italic">var-list</font> <font class="italic">function</font>)</font>, where
<font class="italic">var-list</font> is a list of variables and <font class="italic">function</font> is any function,
creates and returns a closure.  When this closure is applied to some
arguments, all of the value cells of the variables on <font class="italic">var-list</font> are
saved away, and the value cells that those variables had <font class="italic">at the time
<font class="lisp">closure</font> was called</font> are made to be the value cells of
the symbols.  Then <font class="italic">function</font> is applied to the argument.  (This paragraph
is somewhat complex, but it completely describes the operation of closures;
if you don't understand it, come back and read it again.)

	Here is another, lower level explanation.  The closure object
stores several things inside of it.  First, it saves the <font class="italic">function</font>.
Secondly, for each variable in <font class="italic">var-list</font>, it remembers what that
variable's value cell was when the closure was created.
Then when the closure is called as a function, it first temporarily restores
the value cells it has remembered, and then applies <font class="italic">function</font> to the
same arguments to which the closure itself was applied.

	Now, if we evaluate the form
<pre class="lisp">
(setq a 
      ((lambda (x)
	       (closure '(x) (function car)))
       3))
</pre>
what happens is that a new value cell is created for <font class="lisp">x</font>, and its
contents is a fixnum <font class="lisp">3</font>.  Then a closure is created, which remembers
the function <font class="lisp">car</font>, the symbol <font class="lisp">x</font>, and that value cell.
Finally the old value cell of <font class="lisp">x</font> is restored, and the closure is
returned.  Notice that the new value cell is still around, because
it is still known about by the closure.  When the closure is applied,
this value cell will be restored and the value of <font class="lisp">x</font> will be <font class="lisp">3</font>.

	Because of the way closures are implemented, the variables
to be closed over must not get turned into "local variables" by the compiler.
Therefore, all such variables should be declared special.

	In the Lisp Machine's implementation of closures, lambda-binding
never really allocates any storage to create new value cells.  Value
cells are only created (sometimes) by the <font class="lisp">closure</font> function itself.
Thus, implementors of large systems need not worry about storage allocation
overhead from this mechanism if they are not using closures.  See the section
on internal formats.

	Lisp Machine closures are not closures in the true sense,
as they do not save the whole variable-binding environment; however,
most of that environment is irrelevant, and the explicit
declaration of which variables are to be closed allows the
implementation to have high efficiency.
They also allow the programmer to explicitly choose for each variable
whether it is to be bound at the point of call or
bound at the point of definition (e.g., creation of the closure), a choice
which is not conveniently available in other languages.  In addition the
program is clearer because the intended effect of the closure is made
manifest by listing the variables to be affected. 

<div class='section'>4.2 Examples of the Use of Closures</div>
	This section gives some examples of things that can be done easily
and elegantly with closures, which would be difficult to do without them.

	We will start with a simple example of a generator.  A <font class="italic">generator</font>
is a kind of function which is called successively to obtain successive elements
of a sequence.
We will implement a function <font class="lisp">make-list-generator</font>, which takes a list,
and returns a generator which will return successive
elements of the list.  When it gets to the end it should return <font class="lisp">nil</font>.

	The problem is that in between calls to the generator, the generator
must somehow remember where it is up to in the list.  Since all of its
bindings are undone when it is exited, it cannot save this information in
a bound variable.  It could save it in a global variable, but the problem
is that if we want to have more than one list generator at a time, they
will all try to use the same global variable and get in each other's way.

	Here is how we can use closures to solve the problem:
<pre class="lisp">
(defun make-list-closure (l)
    (closure '(l)
	     (function (lambda ()
			       (prog1 (car l)
				      (setq l (cdr l)))))))
</pre>
Now we can make as many list generators as we like; they won't get
in each other's way because each has its own value cell for <font class="lisp">l</font>.
Each of these value cells was created when the <font class="lisp">make-list-closure</font>
function was entered, and the value cells are remembered by the closures.

<!-- Need more exmaples. -->

<div class='section'>4.3 Function Descriptions</div>
<div class='defun'><font class='exdent'><font class='funcname'>closure <font class='italic' color='purple'>var-list function</font></font></font><br>
This creates and returns a closure of <font class="italic">function</font> over the variables
in <font class="italic">var-list</font>.  Note that all variables on <font class="italic">var-list</font>
must be declared special if the function is to compile correctly.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>symeval-in-closure <font class='italic' color='purple'>closure symbol</font></font></font><br>
This returns the binding of <font class="italic">symbol</font> in the environment of <font class="italic">closure</font>;
that is, it returns what you would get if you restored the value cells
known about by <font class="italic">closure</font> and then evaluated <font class="italic">symbol</font>.
This allows you to "look around inside" a closure.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>set-in-closure <font class='italic' color='purple'>closure symbol x</font></font></font><br>
This sets the binding of <font class="italic">symbol</font> in the environment of <font class="italic">closure</font>
to <font class="italic">x</font>; that is, it does what would happen if you restored the value cells
known about by <font class="italic">closure</font> and then set <font class="italic">symbol</font> to <font class="italic">x</font>.
This allows you to change the contents of the value cells known about
by a closure.
</div>

<div class='defmac'><font class='exdent'><font class='funcname' id='let-closed'>let-closed</font><font class="italic"> Macro</font><br></font><!-- end font_exdent --><br>When using closures, it is very common to bind a set of variables with
initial values, and then make a closure over those variables.  Furthermore
the variables must be declared as "special" for the compiler.  <font class="lisp">let-closed</font>
expands into a form which does all of this.  It is best described by example:
<pre class="lisp">
(let-closed ((a 5) b (c 'x))
   (function (lambda () ...)))

<font class="main">expands into</font>

(local-declare ((special a b c))
   (let ((a 5) b (c 'x))
      (closure '(a b c)
         (function (lambda () ...)))))
</pre>
</div>
.eof
</body>
</html>

